Copyright 2007 TeX Users Group.
You may freely use, modify and/or distribute this file.

% (A) One of the schemes supported by Tomas Rokicki's {\DVIPS},
% used by one dialect of Trevor Darrell's {\PSFIG} macro package:

\verb@\special{ps::[begin] <w> <h> <xll> <yll> <xur> <yur> startTexFig}@
% \verb@\special{ps:: doclip}@\hfill\linebreak
\verb@\special{ps: plotfile <eps-file>}@\hfill\linebreak
\verb@\special{ps::[end] endTexFig}@ % \hfill\linebreak

% (B) Variant on the previous theme for Stephan v. Bechtolsheim's {\DVITWOPS},
% generated by another dialect of Trevor Darrell's {\PSFIG} macro package:

\verb@\special{ps: psfiginit}@\hfill\linebreak
% \verb@\special{ps: literal "doclip "}@\hfill\linebreak
\verb@\special{ps: literal <w> <h> <xll> <yll> <xur> <yur> startTexFig}@\hfill\linebreak
\verb@\special{ps: include <eps-file>}@\hfill\linebreak
\verb@\special{ps: literal "endTexFig "}@ % \hfill\linebreak

% (C) The scheme of Anthony Li's {\DVITWOPS}, % Tomas Rokicki's {\DVIPS} 
% used by yet another dialect of Trevor Darrell's {\PSFIG} macro package:

\noindent
\verb@\special{pstext="<w> <h> <xll> <yll> <xur> <yur> startTexFig"}@\hfill\linebreak
\verb@\special{psfile=<eps-file>}@\hfill\linebreak
\verb@\special{pstext=endTexFig}@

\vskip .05in

%% NOTE conflict between two different uses of psfile=

% The six integer arguments preceding \verb@startTexFig@
% represent the desired width and height of the
% inserted figure on the page, 
% and the lower left and upper right corner of its bounding box, 
% all in {\DVI} units 
% (that is, `scaled' points, 65536 per printer's point)%
% \cfootnote{In this case, the bounding box comment in the inserted {\EPS}
% file can be ignored by {\DVIPSONE}, since the {\TeX} macro package
% already had to read the {\EPS} file to position the figure.}. 

% The figure is scaled so as to map the bounding box into a rectangle of
% the specified width and height.
% The {\it upper left-hand\/} corner of this rectangle 
% is placed at {\TeX}'s current point. % check ???

% Note that scaling may be different in the horizontal and the vertical
% direction, something that may lead to unexpected results.
% Isotropic scaling can be forced by making the aspect ratio of the specified
% rectangle on the page match the aspect ratio of the rectangle defined 
% by the bounding box. % in the {\EPS} file.

\noindent
Clipping to the specified bounding box may be requested 
by inserting the line:

\vskip .05in

\verb@\special{pstext="doclip"}@

\vskip .05in

\noindent
after the \verb@startTexFig@ line. % and before \verb@endTexFig@.
%
As in the previous schemes, there may be several % occurrences of
`\verb@psfile=<file-name>@' lines % specials % \verb@\special@s
between \verb@startTexFig@ and \verb@endTexFig@.
% This is useful for inserting prolog and postlog files for a
% particular figure. 

If several figures share the same prolog file, then it may make sense
to read such a common prolog file once at the beginning.
A user prolog file accessible to all included {\EPS} files
% A prolog file 
may be inserted using:

\vskip .05in

\verb@\special{header=<user-prolog-file>}@

\vskip .05in

\noindent 
The user's prolog file is read once and loaded into the same 
Post\-Script dictionary used by {\DVIPSONE}'s procedures.  
In the Post\-Script output by {\DVIPSONE}, 
the prolog file appears after {\DVIPSONE}'s own procedures,
but before any of the actual pages, 
independent of where the corresponding \verb@\special@ occurred 
in the {\TeX} source file.
(See subsection~3.3 for warnings about the use of user supplied prolog files).

\vskip .1in

\noindent
(D) Another scheme supported by {\DVIPS}, 
generated by Tomas Rokicki's {\tt epsf} macro package: 

\vskip .05in

{\narrower

\ivpar % \noindent 
\verb@\special{PSfile=<epsfile> llx=<xll> lly=<yll>@\hfill\linebreak
\verb@  urx=<xur> ury=<yur> rwi=<rwidth*10>}@ % rhe=<rheight> clip=

}

\vskip .05in

\noindent
indicating that the file \verb@<eps-file>@ is to be inserted with the 
{\it lower-left\/} corner of the bounding box of the inserted figure at
{\TeX}'s current point % positioning ?
(Note that here the first two letters in the word `{\tt PSfile}' 
are in upper case).
Four of the arguments specify the bounding box of the figure.
The last argument specifies the requested width of the figure (scaled by 10).
The coordinate system in which the parameters are specified is the
default Post\-Script coordinate system, 
with 72 units per inch (that is, {\TeX}'s `big points' - {\tt bp})
with the origin at the lower left-hand corner of the page. 
The figure is scaled isotropically.

% and height are optional.  
% If both are omitted, the figure is printed at its normal size.
% If only one is specified, then the figure will be isotropically scaled.
% If both are given, horizontal and vertical scaling is applied to fit
% the given bounding box into the specified rectangular space.

\vskip .1in

% following triggered by "=" as separator
% no shift needed - hence no need to read file for BBox

\noindent
(E) The scheme of % used by % {\UNIX}$^{\smlsize TM}$'s 
an older version of {\DVITWOPS}, % on Unix
due to Mark Senn {\it et al\/}, % 
% also supported by Tomas Rokicki's {\DVIPS} ?
used by Gerald Roylance's macro package \verb@psadobe@.
% Stephan v. Bechtolsheim, Bob Brown, Richard Furuta, James Schaad,
% Robert Wells, Neal Holtz, Chris Lindblad, Scott Jones etc etc
In the simplest case this takes the form:

\vskip .05in

\verb@\special{psfile=<eps-file>}@

\vskip .05in

\noindent
indicating that the file \verb@<eps-file>@ is to be inserted with the 
{\it origin\/} of the coordinate system of the inserted figure at {\TeX}'s
current point.
% (So the bounding box given in the inserted {\EPS} file can be ignored.)
% Which means that {\DVIPSONE} need not search for the BBox in the file...
Additional arguments may be used to specify %  horizontal and vertical
scaling, and offsets, as well as clipping: % rotation ?

\vskip .05in

{\narrower

\ivpar
\verb@\special{psfile=<eps-file>@\hfill\linebreak 
\verb@  hscale=<x-scale>@ \verb@vscale=<y-scale>@\hfill\linebreak
\verb@  hoffset=<x-offset>@ \verb@voffset=<y-offset>@\hfill\linebreak
\verb@  hsize=<x-size>@ \verb@vsize=<y-size>}@

% and rotation ?

}

%% if scale > 8.0 it is treated as a percentage and divided by 100.0
%% if scale < 8.0 it is treated as actual scale

\vskip .05in

\noindent
All key-value pairs after the first are optional.
Scales may be given as floating point quantities
(and are {\it not} percentages). 
%% well, Tomas Rokicki's DVIPS supports this WITH percentages for scales...
Offsets and clipping sizes are specified in `big points', 72 to the inch.

% If {\tt hscale} is specified, then the figure is scaled in the
% horizontal direction, and if {\tt vscale} is specified it is scaled
% in the vertical direction.
Different scaling in the horizontal and vertical directions may be specified. 
Note that in this scheme, the clipping rectangle, 
specified by {\tt hsize} and {\tt vsize}, 
is constrained to have its lower left-hand corner at the origin.
%
%% not clear whether this is implemented as it should be ???
%
% the lower left corner of the bounding box.
% does not permit specification of clipping on left and bottom
% The same scheme is apparently used by Tomas Rokicki's DVIPS ?
%% ditto for Tomas Rokicki's DVIPS - except, he uses percentage scaling
% that is, scales are multiplied by 100 in his case...

\vskip 0.1in

%% This asshole scheme conflicts with an earlier one using pstext= psfile=

% following triggered by illustration, postscript, postscriptfile, picture
% /* needshift > 0 if need to shift by (-xll, -yll) */  /* Textures */

\noindent
(F) The scheme for figure inclusion used by James Clark's {\DVITOPS}:

\vskip .05in

\verb@\special{dvitops: import <eps-file> <width> <height>}@

\vskip .05in

\noindent where {\tt <width>} and  {\tt <height>} are the desired
width and height of the included illustration, specified in units 
recognized by {\TeX} % dimensions ?
(that is, {\tt pt}, {\tt pc}, {\tt in}, {\tt bp}, {\tt cm}, {\tt mm}, 
{\tt dd}, {\tt cc}, {\tt sp}---see chapter~10 of the {\TeX}book). 
The illustration is scaled so that it will fit into the specified space.
Scaling is the same in the horizontal and vertical directions---the
illustration is centered in the direction in which there is extra space.
The {\it lower left-hand\/} corner of the bounding box 
% (of the scaled figure) 
is placed at {\TeX}'s current point. 

It is also possible to insert a prolog file using

\vskip .05in

\verb@\special{dvitops: prolog <user-prolog-file>}@ 

\vskip .05in

\noindent
The user's prolog file appears after {\DVIPSONE}'s own preamble, 
but before anything else, 
% independent of where in the file this \verb@\special@ occurs 
independent of where the corresponding \verb@\special@ occurred 
in the {\TeX} source file.
(See subsection~3.3 for warnings about the use of prolog files).
%
To switch the output to landscape mode for one page, 
start the page with:

\vskip .05in

\verb@\special{dvitops: landscape}@

\vskip .05in

\noindent
% at the top of the page.
In landscape mode, {\TeX}'s origin, 
normally 1" below and 1" to the right of the top left-hand corner of the page,
is 1" above and 1" to the right of the lower left-hand corner of the page%
\cfootnote{Note that some dialects of {\TeX}, such as {\YTeX}, center
the text on the page, and so move the origin---this may produce
unexpected results when \verb@\hsize@ and \verb@\vsize@ are
interchanged to match landscape orientation.}.
%
Finally, to include verbatim Post\-Script use

\vskip .05in

\verb@\special{dvitops: inline <PostScript fragment>}@

\vskip .05in

\noindent
Note that in this case the {\DVI} coordinate system is in effect,
using scaled points (65536 per printer's point), 
and with the origin 
1" below and 1" to the right of the top left corner of the page
(See subsection~3.3 for warnings about the use of included Post\-Script). 
%
%% inline, prolog, landscape  DONE !
%
Other uses of \verb@\special@ by {\DVITOPS} are not supported.

\vskip .1in

\noindent
(G) A % One of the schemes 
scheme for figure inclusion supported by ArborText's 
{\DVILASER}$^{\smlsize TM}$:

\vskip .05in

\verb@\special{ps: epsfile <eps-file> <scale-number>}@

\vskip .05in

\noindent
indicating that the file {\tt <eps-file>} is to be inserted with the
{\it lower left-hand\/} corner of the figure's bounding box placed
at {\TeX}'s current point, %% ?
scaled by {\tt <scale-number>}/1000.
Scaling is optional; {\tt <scale-number>} should be an integer.
%
% Without scaling, the user coordinate system has 72 units to the inch%
% Note that other forms of \verb@\special@ usage appropriate for ArborText's
% {\DVILASER}$^{\smlsize TM}$ are not supported. 
% because they depend on insertion of % extensive 
% verbatim Post\-Script code and references to % several 
% functions built into the prolog used by that driver.}.
%
Other uses of \verb@\special@ by {\DVILASER} are not supported.

\vskip .1in

\noindent
(H) The scheme used by Blue Sky Research's Textures$^{\smlsize TM}$, 
which is:

\vskip .05in

\verb@\special{illustration <eps-file> scaled <scale-number>}@

\vskip .05in

%% If scale > 33.3 it is treated as per mille scale and divided by 1000
%% If scale < 33.3 it is treated as the actual scale

% \ipar
\noindent
indicating that the file {\tt <eps-file>} is to be inserted with the
{\it lower left-hand\/} corner of the figure's bounding box placed
at {\TeX}'s current point, %% ?
scaled by {\tt <scale-number>}/1000.
Scaling is optional; {\tt <scale-number>} should be an integer.
%
% Without scaling, the user coordinate system has 72 units to the inch.
%
It is also possible to include Post\-Script program fragments verbatim using

\vskip .05in

\verb@\special{postscript <postscript-fragment>}@

\vskip .05in

\noindent
or, if it is more convenient to place these program fragments in a
file, using

\vskip .05in

\verb@\special{postscriptfile <postscript-file>}@

\vskip .05in

% \ipar
\noindent
In either case, the origin of the coordinate system is at {\TeX}'s
current point. %  and the scale is 72 units per inch.

\vskip .05in

% \ipar
The difference between {\tt illustration} and {\tt postscriptfile} is that 
{\tt illustration} treats the file as an encapsulated Post\-Script file
that is to be positioned in accordance with the bounding box specified in
the file, while {\tt postscriptfile} treats the file as raw Post\-Script
code to be inserted without any additional positioning.
% i.e. there is no %%BoundingBox:

% grestore - gsave sequence not supported

% "picture" not supported because it refers to images in bitmap form.

\vskip 0.1in

% following triggered by space (unless recognized by Textures)
% /* needshift < 0 if need to shift by (-xll, -yur) */  /* DVIALW */

\noindent
(I) The scheme proposed by Nelson Beebe for his driver {\DVIALW},
where %  a sequence of
comma-separated key-value pairs appear, 
starting with the pair {\tt language "Post\-Script"} or {\tt language "PS"}
(Use a space between a key and the corresponding value, not `{\tt =}').
% what macro package uses this ?
The following

\vskip .05in

\verb@\special{language "PS", include "<eps-file>"}@

\vskip .05in

% \ipar
\noindent
% for example,
causes inclusion of the illustration in the file {\tt <eps-file>}.
The included figure is positioned with the {\it upper left-hand\/} % UGH !
corner of the figure's bounding box placed at {\TeX}'s current point. 
If the figure is instead to be treated as an overlay
(that is, using the default Post\-Script coordinate system), 
then use % the form

\vskip .05in

\verb@\special{language "PS", overlay "<eps-file>"}@

\vskip .05in

\noindent
Finally, verbatim Post\-Script fragments can be included using the form

\vskip .05in

\verb@\special{language "PS", literal "<program-fragment>"}@

\vskip .05in

% \endbullets

\noindent
The Post\-Script code following {\tt literal} is placed 
{\it before} the contents of an included file if {\tt literal} occurs in a 
\verb@\special@ that also specifies a file to be `included' or `overlayed'.
%
% The inserted PostScript code can refer to \verb@CurrentX@ and
% \verb@CurrentY@ for the position of {\TeX}'s current point,
% to \verb@PaperHeight@ and \verb@PaperWidth@ for the page dimensions,
% and to \verb@BoxHeight@ and \verb@BoxWidth@ for the size of the
% bounding box of the inserted figure (if any).
% Each is measured in units of 72 per inch ({\TeX}'s big points).
%
The main use of the ability to include {\tt literal} 
Post\-Script in this situation is to insert code for scaling, 
positioning, and clipping,
since there are no key-value pairs for such transformations.
%
Other uses of \verb@\special@ by {\DVIALW} are not supported.

\vskip 0.05in

\noindent 
(J) The command syntax for figure inclusion used by Andrew Trevorrow 
in Oz{\TeX} for the Mac\-Intosh, and in Psprint for Vax VMS,
is also supported, 
but {\it only\/} if the `undocumented' command line flag `{\tt j}' is used.
This is because this form \verb@\special@
does not include any special keyword or
separator that could be used to distinguish it from other usage of
\verb@\special@, or from meaningless text.
Instead the \verb@\special@ starts right off with the name of the file
to be included.
Activation of this feature is somewhat risky.

\endbullets

\vskip 0.05in

\ivpar
\indent
After suffering through this subsection, you will probably agree that:
% it is about time that there be a standard for usage of
% \verb@\special@ for figure inclusion!

\vskip 0.05in

\beginbullets

\bpar A standard protocol using \verb@\special@  for inclusion of figures in
{\TeX} is urgently needed!

\endbullets

